The 640 MEG Shareware Studio 2

home *** CD-ROM | disk | FTP | other *** search

/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / basic / ds40bpds.zip / DS40.DOC < prev next >

Wrap

Text File | 1992-06-03 | 149KB | 3,527 lines

Door Source - Version 4.0B QBX/PDS 7.x VERSION Released May 16,1992 Copyrighted 1989,1989,1990,1991,1992 By Todd Miller Support Boards: PC-Technologies (Sysop Todd Miller) (919) 294-1770 Mail Support: PC-Technologies PO Box 77103 Greensboro, NC 27417-7103 Door Source 4.0B Programmer's Manual - Page 2 Table of Contents Disclaimer and Credits.............................................4 Introduction.......................................................5 The deal on NO registration........................................6 Some Never Nevers..................................................7 Quick Start........................................................8 Loading Door Source.............................................8 First few lines.................................................8 Getting Started....................................................10 Command line options............................................... Door Writing Techniques............................................16 Gathering data from the user....................................19 Making friendly menus...........................................20 Finishing your door................................................23 Getting more out of Door Source....................................25 The definable page sound........................................25 Two fancier input prompts.......................................26 Advanced Techniques................................................29 Extra status line...............................................29 Writing your own I/O routines...................................30 How a door works...................................................32 Converting from 3.2 or before......................................33 Summary of new features............................................34 Appendix A - CALL Syntax...........................................35 Appendix B - Optimizing your door..................................36 Appendix C - Common Questions......................................37 Appendix D - Variable Reference....................................38 Appendix E - Script Commands.......................................41 Appendix F - Command Reference.....................................53 AdjustTimeLimit.................................................54 AllTrun$........................................................55 ANSIMusic.......................................................56 BackSpace.......................................................57 BackSpaceOver...................................................58 BackSpaceToCol..................................................59 BeepSpeaker.....................................................60 BlockSend.......................................................61 Center..........................................................62 ChangeCTS.......................................................63 ChangeDTR.......................................................64 ChangeRTS.......................................................65 CheckCarrier....................................................66 CheckTimeLeft...................................................67 ClrScrn.........................................................68 ColorEasy.......................................................69 CommInkey$......................................................70 CommKeyInkey$...................................................71 CopyAFile.......................................................72 DayOfWeek.......................................................73 DoorBusy........................................................74 EntryIncomm.....................................................75 ExtendedCode....................................................76 ExitDoor........................................................77 FileExist.......................................................78 FileOpen........................................................79 GameInfoUpdate..................................................80 GetTime.........................................................81 HighScores......................................................82 Incomm..........................................................83 MenuManager.....................................................85 MoveCursor......................................................86 NL..............................................................87 Parser..........................................................88 PromptIncomm....................................................89 QSend...........................................................90 RainbowSend.....................................................91 RandNum.........................................................92 ReadUsers.......................................................93 Send............................................................94 ShellToDos......................................................95 Sorter..........................................................96 SysopPage.......................................................97 TimeConvert.....................................................98 ViewFile........................................................99 WaitASec........................................................100 WindowInput.....................................................101 WindowPrint.....................................................102 Windows.........................................................103 WriteUsers......................................................104 Door Source 4.0B Programmer's Manual - Page 4 Disclaimer and Credits ---------------------- This software (including instructions for its use) is provided "as is" without warranty of any kine. Further, the author does not warrant, guarantee, or make any representations regarding the use, or the results of the use, of the software or written materials converning the software in terms of correctness, accuracy, reliabilty, currentnes, or otherwise. The entire risk as to the results and performance of the software is assumed by you. If the software or written materials are defective, you, and not the author or the author's distributors or employees, assume the entire cost of all necessary servicing, repair, or correction. Neither the author nor anyone else who has been involved in the creation, production, or delivery of this software shall be liable for any direct, indirect, consequential, or incidental damages (including damages for loss of business profits, business interruption, loss of business information, and the like) arising out of the use of or inability of to use such software. Distribution of the software is allowed as long as it is in complete form as when you recieved it. Distribution of the files without the documentation is not allowed. Distribution of the libraries made by the installer program is not allowed. Sorry for such a long disclaimer, but you have to cover that legal stuff. QuickBasic (R) is a registered trade mark of Microsoft Corporation PCBoard (R) is a registered trade mark of Clark Development Company (CDC) MS-DOS (R) is a registered trade mark of Microsoft Corporation Door Source is copyrighted Computer City, USA 1988, 1989, 1990, 1991 Troy Getty - For helping in the testing of 4.0 and suggesting a badly needed routine, ShellToDOS. Daniel Sharpe - For letting us put the RainbowSend command into Door Source. Premo Mondone - Who has given me suggestions for 3.0 and above To all my competitors - Who give me inspiration to make this product better than theirs. (And cheaper too!) Door Source 4.0B Programmer's Manual - Page 5 Introduction ------------ Welcome to Door Source! Door Source is a Quick Basic library, intended for using with versions 4.0 and above. Door Source provides you with a collection of routines to help you interface with a bulletin board and the communications port to make a "door", or otherwise referred to as a third party program, that adds onto the board. Some people don't like having to read a large manual, and rather jump right in with both feet and start off, if you would like to quickly start, please read the following two sections after this introduction. It is advised however, that you read Door Writing Techniques, and Getting More out of Door Source too. If you have previously used Door Source, you should refer to Converting from 3.2 or before and also to the Summary of New Features. Door Source will also be referred to as DS in this manual. Door Source is provided to you free of charge, and you can receive technical support at (919) 294-1770 (DATA 2400 max). Door Source users will be given free access to the other nodes after first calling the number above. Files included -------------- Here is a list of files that you should have: DS40 .DOC - Door Source 4.0B documentation DOORSORC.INT - Door Source 4.0B include file DSGAME .INT - Door Source 4.0B include file WINDDEMO.BAS - Window demo using the Window routine MENUDEMO.BAS - Menu demo using the MenuManager routine PRMTDEMO.BAS - Prompts demo using various input routines BLCKDEMO.BAS - A demo using the UserBlock type declaration ERRDEMO .BAS - A demo with the CarrierLossError variable SAMPLE .BAS - A sample door program written with Door Source MANUAL .FRM - A form to order a printed manual with disks LOADQB .BAT - A batch file to make loading DS easier DS00x .DS4 - These are special files with extra routines DSINST .EXE - This will help you select the right object files for the most compact DS library. DSINST .DOC - Documentation on how to use the installer COMPRESS.ZIP - A program to compress the HighScores data files DOORINST.ZIP - A program to install your doors on other boards Door Source 4.0B Programmer's Manual - Page 6 The deal on NO registration --------------------------- This may seem extremely odd, but Door Source is offered 100% completely free. There are no registration fees, no more forms, you don't ever have to send us a thing! Why? Many years ago when Door Source was first started on, I realized the need for a better product in the field of door tool kits, and I decided that I would try to fill that gap, but at no charge. All the other door kits (that I know of) ask for some kind of registration, and I think this is truly one of the first that requires none at all. But I do like to know who is using Door Source, and a call to PC-Technologies just to say thanks, or, better yet, to give a suggestion for improvements, is always appreciated! If you have a specific need for a routine or improvement to the Door Source library, you can call and tell it to me, and you're guaranteed that 90% of all improvements or suggestions are added within a few releases! Door Source 4.0B Programmer's Manual - Page 7 Some Never Nevers ----------------- There are some things you never should do when using Door Source. What you shouldn't do is listed below, and since most people won't believe it unless they know why, we have included reasons, and in some cases, alternate routines to use instead. Never use CLS, VIEW PRINT, PRINT, LOCATE, or COLOR because Door Source handles all screen output, and using these will cause Door Source to lose some of its pointers on the screen. Also, on systems using DesqView, it could cause lock ups. Never use OPEN COM or ON COM, because Door Source doesn't use Quick Basic's communication routines, and using these would cause a confliction of interrupts between Door Source and Quick Basic, that would lead to unpredictable results. Never use SCREEN, because Door Source handles screen output, it wouldn't be able to follow your change to a different mode, and would cause serious problems. Never use END or SYSTEM, because that would cause Door Source to leave its interrupt handlers still in place and the next program to run would probably crash. Never use DEFINT, or any of DEF beside DEF FN, because Door Source expects variables to be passed that are in single precision format (the default of Quick Basic). Never use PLAY or SOUND, because it will cause a sound when the sysop using your door program may not want sound, like in the middle of the night, use BeepSpeaker instead of BEEP or SOUND, and AnsiMusic instead of PLAY. Door Source 4.0B Programmer's Manual - Page 8 Quick Start ----------- Installing and loading Door Source ---------------------------------- After you have unzipped the Door Source file (assuming that you have since you're reading this), you will only need to copy a few files into your Quick Basic sub-directory. All you will need to do is run DSINST, the Door Source Installer, and then copy DS40.QLB and DS40.LIB into your QuickBasic directory. Now you are ready to load up Quick Basic, which you can do by typing: QBX [your program name] /L DS40 You also can add on a /CMD[command$ string] that would place what you put there into COMMAND$ inside Quick Basic. This would be used to easily specify your configuration file for the door, an example is this: QBX MYDOOR /L DS40 /CMDTESTDOOR.CFG LOCAL Putting a space in between the /CMD and TESTDOOR.CFG will cause Door Source not to recognize your configuration file properly. The First Few Lines ------------------- Once inside the Quick Basic environment, ready to write a new door program, the first line should always be: ' $INCLUDE:'DOORSORC.INT' This will tell Quick Basic to include this file into your program. What this file contains is declarations for the Door Source routines (to help eliminate errors), a COMMON SHARED block, along with a few CONSTant declarations. At the end of the file, it calls the InitDoor routine, which starts Door Source rolling. The next line after that in your program should be: PROGNAME$ = "My Door" You should replace "My Door" with the name of your door. But make sure that it is in quotations, or Quick Basic will give you a Type mismatch error. The name placed in this string shouldn't exceed 20 characters. The next line should be: RELEASE$ = "1.0" Door Source 4.0B Programmer's Manual - Page 9 This is the release number (or version number) of your door program. It should be less than 6 characters long, and can contain letters and numbers (A-Z, a-z, 0-9), as well as punctuation. CALL ClrScrn CALL ClrScrn should be the next line in your program. It will clear the screen, and now you almost ready to go on about your door, however, there is one last thing. In the DOORSORC.INT, when it calls InitDoor, it will leave a file open for you (file number 1) and this file is the configuration file. If you would like to INPUT anything from it, do that here, and once you are done inputing anything else that was added onto the configuration file, or if you didn't input anything at all, you will need to add one last line, which is: CLOSE #1 Now you are ready to write your door. A few basic routines that you should look up are Send (on page XX), Incomm (on page XX), ClrScrn (on page XX), and NL (on page XX). I'm sure you are sick of reading this manual by now, but these are the 4 most basic commands. You should also read Testing Your Door before you try to run the door for the first time, because there are a few things to make sure that you have in your program, and on your disk in order for it to work. Door Source 4.0B Programmer's Manual - Page 10 Getting Started --------------- Writing a simple program in Door Source --------------------------------------- Before you can really do anything, you'll need to run the Door Source Installer, DSINST, to create DS40.QLB and DS40.LIB. Before loading Quick Basic, make sure that you have set the proper environment strings to direct Quick Basic to your Door Source directory (if you have one). You will also need to make a configuration file that you can use to test a simple door with. The Door Source configuration file format is a simple four line file. You can make it longer if your door needs information from it (see Advanced Techniques). An example configuration file might be called TESTDOOR.CFG and look like this: C:\PCB\PCBOARD.SYS PC-Technologies Todd Miller The first line is a drive/path/filename to the bbs interface file, and the second line is the name of the bbs using the door. The third line is the first name of the sysop and the fourth line is the last name of the sysop. Now, load up Quick Basic, with the /L (library) switch on it like this: QBX /L DS40 That will load up Quick Basic and the Door Source library. Two other switches that you might use when loading Quick Basic are: /RUN - This is put at the beginning of the line right after QB and will make Quick Basic run the file specified. /CMDMYCONFIG.CFG - The /CMD option always comes at the end, and what comes DIRECTLY after the /CMD will be loaded into the COMMAND$, this simulates what you would have if someone loaded your program like this: MYDOOR MYCONFIG.CFG The MYCONFIG.CFG would be put in the COMMAND$, but if you want to test doors inside Quick Basic, you should use this option, or set the COMMAND$ from the Run menu in Quick Basic. Door Source 4.0B Programmer's Manual - Page 11 Once Quick Basic is loaded, you should press ALT-R to get the Run menu, and the select Modify COMMAND$ (If it isn't listed, then go to the options menu and select Full Menus, then try again). Now enter in the name of the configuration file that you made earlier before loading (If you didn't make it, you can shell to dos from the File menu and make it there). Put after the configuration filename, the word LOCAL. LOCAL will tell Door Source to read the configuration file, but not to use the BBS interface file. Door Source will prompt you for a name, and if you want to use ANSI graphics. This way, you don't have to worry about making a test PCBOARD.SYS, DORINFO1.DEF, CALLINFO.BBS, or DOOR.SYS. If you didn't specify LOCAL, it would look for the bbs interface file that you gave it. Now type the following program into Quick Basic: ' $INCLUDE:'DOORSORC.INT' PROGNAME$="Hello World" RELEASE$="1.0" CALL ClrScrn CLOSE #1 CALL Send("Hello World!",No,Yes,10) CALL Incomm("How are you today, @FIRST@ ?",No,No,14) CALL ExitDoor Press the F5 key and the program will run. If you receive an error, refer to Common Questions to find a solution. You should see Door Source ask you for a name, and if you want ANSI graphics. Then the screen will clear and it will say Hello World! in High Intensity Green, and the beneath that it will show How are you today, with your first name. Enter in anything you want and press enter. It will then say Closing Door... and more. You'll also notice that at the bottom of the screen is a status line, and it will be discussed later in this section. Now let's find out how this program works. First, the INCLUDE file has a lot of DECLAREs in it and a COMMON SHARED block, it also makes a CALL to the Door Source routine InitDoor. Inside InitDoor, Door Source will read the configuration file, process the bbs interface file (in this case, it will ask you for your name and if you want ANSI instead), and it will set up the communications port if it is going to be used. In the next two lines, you set up two variables. PROGNAME$ should be the name of your program. RELEASE$ should be the version number of your program. Door Source will display these on the status line. PROGNAME$ shouldn't be bigger than 20 characters Door Source 4.0B Programmer's Manual - Page 12 and RELEASE$ shouldn't be bigger than 5 characters. They both can contain A-Z, a-z, 0-9, and punctuation. Then you make a call to the Door Source routine ClrScrn, which clears the screen (local and remote), and updates the status line. At this point, if you had added onto the configuration file, you would read it here, but since we didn't, we just close the file that InitDoor left open for us. The first four lines of the program above should be the first four lines in all of your doors, except you would replace what PROGNAME$ and RELEASE$ with information for your door. Send is a Door Source routine that outputs (local and remote) a string, and can optionly beep the speaker, and send a enter when done. The number is the color number, here's the format for calling Send. CALL Send("Hello World!", No, Yes, 10) ^ ^ ^ ^ | | | Color to use | | Send enter when done? | Beep the speaker when done? What to output Incomm is another routine that outputs first and then waits for input back. There are many options that you can use with Incomm, most which are in global variables, which are covered in the reference for it. Here's the way to call Incomm: CALL Incomm("How are you today, @FIRST@ ?", No, No, 14) ^ ^ ^ ^ | | | Color to use | | Limit the length? If | | so, max length. | Send enter before input? What to output first You may have noticed how @FIRST@ wasn't displayed on the screen, but your first name was instead. That's because that when Door Source sees one of these, it knows to replace it with what you want instead. There is a complete list of these in Appendix D. The last call is to ExitDoor, which closes up Door Source files and removes the Door Source interrupt handlers. If you use END instead of ExitDoor, then the interrupt handlers will remain in place, causing the next program to run to crash. ExitDoor will also insure that the caller stays connected while he/she is transferred back to the bbs. Door Source 4.0B Programmer's Manual - Page 13 Colors ------ Door Source can support foreground and background colors. There are three different ways that you can use and change colors too. Here's a color chart: # Name Hex Foreground Background 0 Black 0 Y Y 1 Blue 1 Y Y 2 Green 2 Y Y 3 Cyan 3 Y Y 4 Red 4 Y Y 5 Magenta 5 Y Y 6 Brown 6 Y Y 7 White 7 Y Y 8 Gray 8 Y N 9 HiBlue 9 Y N 10 HiGreen A Y N 11 HiCyan B Y N 12 HiRed C Y N 13 HiMagenta D Y N 14 Yellow E Y N 15 HiWhite F Y N Way #1 to use color ------------------- CALL Send("Hello!",No,No,12) CALL Send("Bye!",No,Yes,10) This would output Hello! in high intensity red and on the same line it would put Bye! in high intensity green. Way #2 to use color ------------------- CALL Send("Hello!",No,Yes,HiRed) CALL Send("Bye!",No,Yes,HiGreen) This would output the same thing as above, the only difference is that it is easier to read. Way #3 to use color ------------------- CALL Send("Hello!@X0ABye!",No,Yes,12) This would output the same as the first and second way, but this one does it with one string. The whole key to this method is the @X0A code in the middle. It tells Door Source to change colors. Door Source 4.0B Programmer's Manual - Page 14 Color Code ---------- Here's how to use the special color codes: @X0F ^^^^ |||Foreground color ||Background color |Second part of signal code First part of signal code You can also change the background color by setting the variable BackGroundColor to a color number on the chart above that is valid a background color (0-7). Command Line Options -------------------- Door Source has numerous command line options in order to provide flexibility with most computer systems. Here is a list: LOCKED:xxxxx - Forces Dooor Source to lock the modem at the speed given. LOCAL - Forces Door Source to run in local mode. This is really meant for testing purposes, but it still reads the configuration file, but doesn't read the bbs interface file. NETWORK - Forces file sharing to be active incase you are using something other than SHARE to manage file locking. IRQ=n - Lets you change the IRQ used for the com port specified in the bbs interface file. (See below for more information) ADDR=&Hnnnn - Lets you change the address used for the com port specified in the bbs interface file. (See below for more information) PS2 - Forces the PS/2 IRQs and addresses if a PS/2 isn't detected (Normally it is, but you can't always tell!) RBBS - Forces Door Source into RBBS/QBBS mode WILDCAT - Forces Door Source into Wildcat 2.0 mode DOORSYS - Forces Door Source into 31-Line DOOR.SYS mode PCB121 - Forces Door Source into PCBoard 11.8/12.x mode with COM 1 active PCB122 - Forces Door Source into PCBoard 11.8/12.x mode with COM 2 active PCB14 - (DEFAULT) Forces Door Source into PCBoard 14.x mode Door Source 4.0B Programmer's Manual - Page 15 When you use the IRQ or the ADDR option, you must include the other. You can't use just the IRQ and not the ADDR, and you can't use just the ADDR and not the IRQ. Here's a chart with the STANDARD IRQs and addresses for the PS/2s and IBM PCs: Non PS/2 Com port IRQ Address 1 4 &H3F8 2 3 &H2F8 3 4 &H3E8 4 3 &H2E8 5-8 4 &H3F8 PS/2 Com port IRQ Address 1 4 &H3F8 2 3 &H2F8 3 3 &H3220 4 3 &H3228 5 3 &H4220 6 3 &H4228 7 3 &H5220 8 3 &H5228 Door Source 4.0B Programmer's Manual - Page 16 Door Writing Techniques ----------------------- When writing a door, you should keep three concepts in mind, they are: 1) Compatibility 2) Flexibility 3) Multi-node A compatible door is a door that easily runs on several bbs types. Door Source currently supports PCBoard 11.8+, PCBoard 14.x, WildCat, RBBS/QBBS DORINFO1.DEF, and the 31-line version of DOOR.SYS. Modifying specific detailed parts of the user's information makes the door less portable, since not all systems have the same information as others. A flexible door is one that allows the sysop to EASILY tell the game where things are, and to set the options that they want. Options like a tournament mode, turns per day, plays per day, etc,... are good options to have. Letting the sysop define text from the door is stretching this a little, but some sysops like this feature. Of course it does mean a lot of work on your part too. A multi-node door is often the hardest to write, but not if you know how. Really it is very easy, easier than most think. You first have to decide how multi-node you want your door to get. For example, you might not won't to try to program something to let two players on at the same time attack each other, so maybe you don't let on go into the same sector as another that is currently on, or you could go for the more complex way and do a one-on-one active battle mode (which players would like). But the one thing all multi-node doors must do is to share files correctly, and the way to do this is to open files as SHARED, and to LOCK and UNLOCK individual records. You will also want to keep in contact with other nodes playing your door at the same time, and this can be done with a simple file that would be organized by node. It would tell the other nodes if it was running maintenance (so the others would play while it was), or to tell the other nodes where someone is. In the Door Source Door tool kit, it contains routines to maintain a file, and others to help make your door more multinode. A multi-node door is always praised by the sysops of a multi-node system. Quick Basic problems -------------------- Quick Basic does have a few problems, and you will encounter them if you are working on a large door project. You will probably encounter a "Out of Stack Space" or a "Out of Data Space" error. I've found that exiting to DOS and then coming back will usually solve the problem. If not, then its time to do some work on your program. If you know that you're door will be large, or if your door gets larger than you expected, then here are a few tips on how to get rid of these problems, or to prevent them: Door Source 4.0B Programmer's Manual - Page 17 1) Use variables, not constants. When you call a routine, like Send, and pass it a constant, the space that the constant used is not released for other programs to use. Instead, it stays in memory until your program quits. So call Send or other routines this way, by defining your variable first. Lin$="Hello!":ColorToUse=10 CALL Send(Lin$, No, Yes, ColorToUse) If you didn't set up the variables before hand, you would have just used up 12 bytes of stack space that wouldn't be made available for other things. (I didn't miscount, a string has a 4 byte discriptor on it.) 2) Use MAKEDS so that your Door Source library will be as small as possible, and so it won't take up extra space with routines you don't need. 3) Use as few variables as possible. You should set aside two or three variables for your loops, a few for input, and a few for output, etc,... Just don't go around putting in new variables, because it will eliminate stack space. 4) If you are using your own COMMON SHARED block, eliminate all unnecessary variables from it, and don't declare a function or subroutine as STATIC unless necessary. Large doors ----------- When writing LARGE doors with Door Source, you should use a multi-module program. To create a new module, you must select the Create file option from the file menu (full menus only). Here are some tips for writing large doors: 1) Make a COMMON SHARED block for each of your modules that has commonly used variables. 2) Include the DOORSORC.INT at the beginning of each module so that it can use the Door Source routines and variables. 3) Make as many things as possible a routine or a function, and place those routines and functions into a module of their own (You could even have several modules of routines). 4) Remember that you can't GOTO or GOSUB to a line number or a label in another module. Door Source 4.0B Programmer's Manual - Page 18 5) Anything that is done more than once is a good candidate for routine or function, even if it just calculates a score or shows lots of information. 6) When calling routines (Door Source or your own), pass variables, not constants to them. Door Source 4.0B Programmer's Manual - Page 19 Gathering Data from the User ---------------------------- When writing your door, you will want to keep a consistent, but friendly and easy to use approach to receiving information back from the user. Using the PromptIncomm or EntryIncomm is a good way to gather a limited amount of data, PromptIncomm is most useful for yes and no questions, and for amounts. EntryIncomm is good for long replies (sentences, names, etc,...). You can also vary Incomm in a number of ways, the Incomm routine is the kernel for PromptIncomm and EntryIncomm. You can write your own routine to first do your special prompt and then call Incomm. For example, if you wanted to make a prompt that used RainbowSend so the prompt is lots of different colors, you could do this: SUB RainbowInput(Text$, LimitField) CALL RainbowSend(Text$, No, No, 11) CALL Incomm("", No, LimitField, Last.Clr.Used) END SUB This would be output Text$ (the prompt) using RainbowSend first, then use Incomm to receive the data. The variable, Last.Clr.Used, is a Door Source variable that has the number of the last color used stored in it. If you have specific keys that you want the user to use and to lock out the others, use the Table$ and Default.Table$ to limit the input to certain keys, for example: Table$="YN" CALL Incomm("Do you want to quit (Y/N) ? ", No, 1, 14) Table$=Default.Table$ The above example first sets Table$ to equal YN, now Door Source will only allow the user to input the letters Y and N (Lower case will NOT work, you have to add in the lower case letters too!). The last line sets Table$ back to the default (when Door Source starts, Table$ is already at the default). This is very important so that you don't accidentally keep limiting input when you don't want to. Also, NEVER change Default.Table$, doing so will make it only harder on you to undo the Table$ setting. You don't have to worry about adding in characters like backspace or enter, because Door Source assumes that you will want to let the user use those keys. Table$ does not affect any output routines, only the Door Source input routines (except CommInkey$ and CommKeyInkey$ functions) Door Source 4.0B Programmer's Manual - Page 20 Making friendly menus --------------------- Friendly menus (to you and the user) are menus that can be aborted in the middle of display. To make a friendly menu in Door Source, define a array and put your menu in it. This also makes it easy for you to make a quick change to one or all of your menus if you have all of the arrays in the same place. An example of how to make a friendly menu would be: CONST Main.Menu.Length = 5 DIM Main.Menu$(5) Main.Menu$(1)="(1) Quit" Main.Menu$(2)="(2) Quit" Main.Menu$(3)="(3) Quit" Main.Menu$(4)="(4) Quit" Main.Menu$(5)="(5) Quit" CALL BlockSend(Main.Menu$(), No, Main.Menu.Length) If the user was to press the space bar, CTRL-X, or CTRL-K while the menu was displaying, it would stop displaying and let your program go on to receive the input. Another form of the friendly menu (but doesn't allow aborting) is using MenuManager to display your menu, and allows ANSI users to use a scroll bar to scroll up and down and make their choice, and allows non-ANSI users to enter their selection. Presenting information in a compact format ------------------------------------------ Displaying ten, twenty character long lines, on ten separate lines is a waste of space. Instead, you could compact the display to five lines, or even less. Setting TabSpace in between calls to one of the Send routines will let you make a nicely formatted display, for example: CALL Send("Info #1:"+Info1$, No, No, 10) TabSpace = 40 CALL Send("Info #2:"+Info2$, No, Yes, 10) CALL Send("Info #3:"+Info3$, No, No, 10) TabSpace = 40 CALL Send("Info #4:"+Info4$, No, Yes, 10) Would look like: Info #1: Something Info #2: Something else Info #3: Anything Info #4: Anything else! Door Source 4.0B Programmer's Manual - Page 21 If you want to display information from an array in a compact format, you could do this: Stack = 0 FOR X = 1 TO 10 IF Stack = 0 THEN CALL Send("Info :"+Info$(X), No, No, 10) TabSpace = 40 Stack = 1 ELSE CALL Send("Info :"+Info$(X), No, Yes, 10) Stack = 0 END IF NEXT X IF TabSpace = 40 THEN TabSpace = 0 In the above example, the variable Stack changes from 0 to 1 and back again to keep track of whether or not it's time to tab over to column 40 or to end the line. The IF after the NEXT X makes sure that you aren't set at column 40 for your next output when you don't want to be. You could also put in another IF block inside the FOR loop to let you decide whether or not you have any information to display or not. You could also modify all the above examples so that you could have three columns and not just two. The Configuration File ---------------------- You can make the configuration file for your door program larger than what Door Source requires it to be, and you can read in the information yourself too. Door Source automatically reads in the first four lines of the configuration file and sets everything up for you to read the rest. Reading more from the configuration file is simple: ' $INCLUDE:'DOORSORC.INT' ProgName$="Configuration Reader" Release$="1.0" LINE INPUT #1, ExtraInfo$ LINE INPUT #1, ExtraNumber CLOSE #1 CALL ClrScrn Even though there is no open statement, Door Source opened the file and read the information from it already (It did this from in the DOORSORC.INT). Remember to close the file after use, even if you don't use it at all. The only limit to how long your configuration file can be is the disk space and the amount of memory you can use to store the information. The configuration file can not be in a random access format, only sequential. Door Source 4.0B Programmer's Manual - Page 22 Testing your Door ----------------- The easiest way to test your door is to run it from inside the Quick Basic environment. You first have to have three things done so that you can, and they are: 1) Have a sample configuration file in the Quick Basic directory. 2) Load Quick Basic with the /L option and DS40 after it For example: QB /L DS40 /CMDTESTDOOR.CFG LOCAL 3) Load Quick Basic with the /CMD option and your configuration file's name after it with the word LOCAL. (See above example) If you forgot to load with the /CMD option, you can set it from inside Quick Basic from the Run menu (Modify COMMAND$). Now all you have to do is press F5 to run your program. If you have any problems, refer to Appendix C - Common Questions. Door Source 4.0B Programmer's Manual - Page 23 Finishing your Door ------------------- To eliminate all possible problems, you should first thoroughly test you door in two manners, logically, and unlogically. When you are logically testing it, you should use your door the way you designed it to be used, noting the little problems as you go. Then when you unlogically test it, you try testing your program in a way completely opposite of how you designed it. This method is a through method to debug your program. You will find most of the errors through this method, but then there are always situations that even you didn't think of in either of these manners. To finish a door you will need to compile to door into a EXE format. This way you can use the door without having to load QuickBasic to run your doors. Since Door Source doesn't use Quick Basic's communications routines, you CAN compile your door to be a stand-alone program, that doesn't need BRUN45.EXE. If you prefer to not make it a stand-alone, you do not have to use a patched version of BRUN45.EXE like other door packages require. In order to compile your program, you must go to the Run menu and select Make EXE. It will compile your program in memory and then a window will pop up asking what you want the final file name of the program to be, and other options. Do not select the produce debug code option, it will only make your program larger and slower, and allow people to break it in the middle by pressing CTRL-Break. After you have everything like you want it, select one of the button on the bottom of the window to start the process. Of course, you'll need to provide some documentation for your door, and good documentation should have some of these sections listed here: Table of contents Disclaimer Overview/Summary of the door List of files in archive Configuration file setup Command line options Batch file setup Customization instructions List of function/ALT keys Possible errors/Troubleshooting A good disclaimer is always something that is hard to come by, here is a disclaimer that pretty much covers you: This program and other files associated with it are not guaranteed to be bug free or virus free. We are not responsible for any damages of any kind, including profit loses and data loss, that relate directly or indirectly to these programs and files. You may distribute this program, as long as it is in unmodified form with all the files originally included. Door Source 4.0B Programmer's Manual - Page 24 You may wish to add/change/delete something from this one, but it is a pretty good one. A overview or summary of the door would be a simple explanation of exactly what your door does, no specifics really. The configuration file section should show a sample configuration file, and give a sentence or two on each line in the file. The command line options should show the user how to configure the door to run with his system. Refer to the chapter on command line options to put into your documentation. The batch file setup should show a few example batch files, and telling you if you need to add it in your daily event, etc,... The customization section should tell the sysop that uses your door how to better customize it to what he needs. Some examples might be aliases allowed/not allowed, location of files, prompts, etc,... The list of function keys is basically this: F3 - Printer toggle F4 - Page bell toggle F5 - Shell to DOS F7 - Caller alarm toggle F8 - Return caller to board F10 - Start sysop chat ESC - Enter sysop chat ALT-X - Drop to DOS after caller logs off ALT-N - Sysop next on flag Troubleshooting should list a few possible errors that might occur, and how to solve them. Like if error number 53 (File not found) occurs, then search your configuration file for a misspelled filename or a wrong path. If error 61 (Disk full) occurs, free up disk space. Some errors can't be solved, and you could list those and have them call a bulletin board for more help. Door Source 4.0B Programmer's Manual - Page 25 Getting more out of Door Source ------------------------------- This section and the following section, Advanced Techniques, are very closely related. With Door Source 4.0B, it is basically possible for you to write your own input and output routines using out base routines to do the dirty work. The difference in between this section and the next is simply that this tells you how to take advantage of some of the new variables and features, and the next section tells you more on programming more advanced things with Door Source. The definable page sound ------------------------ You can easily change the sound of the SysopPage routine by setting 3 variables - PageSound.1, PageSound.2, and PageSound.3 The sound generated is in the order of PageSound.1, then PageSound.2, and then the final sound is PageSound.3. The numbers you put in PageSound should be in the acceptable range of the SOUND command, which is somewhere around 45-32767. A page sound of 200, 400, 600 would make a sound that starts out low, then the next sound is about double the pitch of the first, and the third is double the pitch of the second. Its possible to create a variety of different sounds with this, try experimenting with the SOUND command first to find what you like the best. The duration of the sounds is set, and can't be changed. Example: PageSound.1=200 PageSound.2=400 PageSound.3=600 CALL SysopPage(Answered) Filtering your input -------------------- Sometimes, you may want to limit the input to a question to a few letters, or selectively not recognize certain characters. To do so, you should set the Table$ variable. An example would be: Example: Table$ = "YNyn" CALL Incomm("You can only type Y and N:",No,1,15) ' Anything else besides Y,N,y,n that the user types is ' not displayed or recognized. Backspace and enter CAN NOT ' be filtered out. Table$ = Default.Table$ ' This is necessary to reset the filter back to normal, ' if you didn't do this then you'll have problems with ' later Incomm commands still being restricted with the ' filtering. Output: You can only type Y and N:Y Door Source 4.0B Programmer's Manual - Page 26 Protecting input from prying eyes --------------------------------- When a password or something secret needs to be concealed, you can now set a "substitution character" that will be displayed in place of what the user really types. You can make the character anything you wish, but making it a null turns it off. Example: Protected.Input$="*" ' Now shows a * in place of text CALL Incomm("Password:", No, No, 15) Protected.Input$="" ' Turns it off - Back to normal display Output: Password:****** Two fancier input prompts ------------------------- EntryIncomm ----------- EntryIncomm prints out a field of (----) above the area where the user's input will be displayed. The size of the field is based on how big you make the field. Good for ANSI and NON-ANSI! Example: CALL EntryIncomm("Your new name:", 25, LightGreen, Yellow) ' ^ Field size Output: (-------------------------) Your new name:Zantigahicatal PromptIncomm ------------ PromptIncomm is most useful in ANSI cases, but will handle non-ansi well too, but the purpose of the routine is defeated then. What it does is create a field similar to the EntryIncomm but the field is on the same line as the input. The second text field is the "default field" tells the user what it defaults to if they press enter, but its up to you to interpret them pressing enter. You can pass a string as the second parameter, and it will use that instead of one of the already programmed constants. The constants are: Default1 = (Enter=no) Default2 = (Enter=none) Default3 = (Enter=quits) Example: CALL PromptIncomm("Do you wish to quit",Default1, LightGreen, 1, Yellow) ' ^ Field size Output: Do you wish to quit (Enter=no) ? (N) Door Source 4.0B Programmer's Manual - Page 27 Unabortable ViewFiles --------------------- Do you want to force the user to see out an entire file? Its easy to block the abort codes by setting the variable No.Abort to YES, then when the user tries to abort, it won't let him. However, if more prompts are still offered, answering NO to it will stop the display. Example: No.Abort = YES CALL ViewFile("MYFILE.ANS", No, No, No) No.Abort = NO ' Reset it back to normal Disabling carrier checking -------------------------- How would you like to turn off carrier checking for a call back verification program of some sort, or something along those lines? Try setting Carrier.Check to YES, and Door Source will *IGNORE* the carrier detect flag. If the user drops carrier, you'll have to handle and detect yourself! Example: Carrier.Check = No ' Disables carrier checking Carrier.Check = Yes ' (Default) enables carrier checking Checking the baud and the carrier, setting DTR, CTS, and RTS ------------------------------------------------------------ Checking the baud rate ---------------------- The variable Baud& has the baud rate stored in it. Here's what the number in it means: 1 - Local mode 300 - 300 baud 1200 - 1200 baud 2400 - 2400 baud 4800 - 4800 baud 9600 - 9600 baud 19200 - 19,200 baud 38400 - 38,400 baud 115200 - 115,200 baud Since some boards run with their modem locked, Door Source will give you the locked baud rate in Baud&, but the true connect speed is in TrueBaud& Checking the carrier -------------------- The routine CheckCarrier will tell you if a carrier is present. Example: CALL CheckCarrier(CarrierFlag) IF CarrierFlag = NO AND Baud& > 1 THEN CALL ExitDoor ' Carrier lost! END IF Door Source 4.0B Programmer's Manual - Page 28 Setting the DTR, CTS, and RTS ----------------------------- DTR --- The DTR (Data Terminal Ready) when on normally means that you are on-line, and have a connection. However, on most modems, turning it off while it is on will break the connection. Example: CALL ChangeDTR(YES) ' Turn DTR on CALL ChangeDTR(NO) ' Turn DTR off CTS Control On/Off ------------------ CTS (Clear To Send) is used to signal the other modem that it is ok to send characters. Modems that don't preform error checking or UARTS that don't have buffers may require CTS flow-control to be on during high-speed file transfers. Example: CALL ChangeCTS(YES) ' Turn CTS control on CALL ChangeCTS(NO) ' Turn CTS control off RTS --- RTS (Request To Send) is used by most auto-dial modems to see if a computer is ready to receive data from the modem. If the RTS signal isn't detected, some modems may refuse to accept modem commands or send result codes. Example: CALL ChangeRTS(YES) ' Turn RTS on CALL ChangeRTS(NO) ' Turn RTS off Automatic more prompts ---------------------- If you're displaying lots of information, like programmed in documentation, and you don't want to keep track of when you need to show a more prompt or a press any key prompt, just simply set the AutoMore variable to one of the settings: 0 Disables the prompts (default) MorePrompt (Or the value 1) Causes automatic more prompts PressKeyPromp (Or the value 2) Causes automatic press any key Example: AutoMore = MorePrompt The variable Lines.Since will tell you how many lines have been sent SINCE the last ClrScrn WITH one of the Send routines or Incomm routines. The automatic prompts are by default not enabled, and when enabled, they occur every 23 lines. Door Source 4.0B Programmer's Manual - Page 29 Advanced Techniques ------------------- Door Source has several new features that are more program related, that are just a little bit to hard to put in the previous section, Getting more out of Door Source. The extra line status line -------------------------- Normally, Door Source has lines 24 and 25 in use with its status line, but if you have some information of you're own that you'd like to put on it, now you can by using the GameInfoUpdate routine with the variable GameInfoCol. The only major change you have to make to your program is to use the DSGAME.INT file instead of the DOORSORC.INT file, and you'll need to write a routine to do the status line updating. First of all, the Door Source status line is moved up to lines 23 and 24, and we leave 25 for your use. You call the GameInfoUpdate routine like you would call print, for example: ' $INCLUDE:'DSGAME.INT' . . (Later in the program) Background . \/ CALL GameInfoUpdate("This is on the 25th line!", No, 14, 7) ^ Text ^ ^ | Foreground Enter The background is the last number, and the color you specify is the foreground color. The enter parameter is like the ; on a print command, telling it no keeps the current position at that spot, but yes will start at column 1 when you do the next GameInfoUpdate. But what if you want to position the cursor somewhere on the line without printing to that location? Or what if you want to know where the cursor is? You can tell both of these by looking at the GameInfoCol variable. For example: A = GameInfoCol ' A now contains the horizontal position ' of the cursor on line 25. GameInfoCol = 30 ' With the next GameInfoUpdate call, it ' will start printing at column 30. Now the only thing missing is your interfacing this into your program. The easiest way to do this is to write a new ClrScrn routine, that you call in place of ClrScrn, this is necessary because ClrScrn doesn't update your line when called, so you'll have to do it. Here's an example of a new ClrScrn: SUB ClearTheScreen CALL ClrScrn CALL GameInfoUpdate("This is on the 25th line!",No,14,7) END SUB Door Source 4.0B Programmer's Manual - Page 30 Writing your own output routines -------------------------------- With Door Source, you can virtually write your own output routines for use with your program. The kernel for all of our output routines is the Send1Line routine. It will send one line out to the local and remote display, and will decode the substitution codes too! All that's left for you to do is to write your own routine that calls this routine. For example, say you wanted to write a routine that would colorize all of the letters that are the capital A, then you might do this: SUB ColorizeTheA(Text$,AColor$,RegularColor$) FOR X=1 TO LEN(Text$) IF MID$(Text$,X,1)="A" THEN CALL Send1Line(AColor$+MID$(Text$,X,1)) ELSE CALL Send1Line(RegularColor$+MID$(Text$,X,1)) END IF NEXT X END SUB The variables AColor$ and RegularColor$ would store the @X color codes for the colors for A's and other letters. Writing your own input routines ------------------------------- You can write your own input routines too with Door Source. The main kernel for the input routine is CommInkey$, and a few other routines supplement the features offered in Incomm. An example input routine that is very simple might be: SUB GetInput DO A$=CommInkey$ IF A$="" THEN A$=INKEY$ LOOP UNTIL A$<>"" ARG$=A$ END SUB You should also be aware that all filters, and special variables that affect input with Incomm do NOT work with CommInkey$, you have to program in support for them yourself if you want them. The GetInput routine above would wait for a key to be pressed on the local or remote keyboard. Now say that you want to echo the character to the screen and to the remote screen, you'd do this: SUB GetInput DO A$=CommInkey$ IF A$="" THEN A$=INKEY$ LOOP UNTIL A$<>"" ARG$=A$ CALL Send1Line(A$) ' Echos the character END SUB Door Source 4.0B Programmer's Manual - Page 31 Now maybe you want to trap the function keys, you could do this: SUB GetInput DO A$=CommInkey$ IF A$="" THEN A$=INKEY$ LOOP UNTIL A$<>"" ARG$=A$ IF LEFT$(A$,1)=CHR$(0) THEN CALL ExtendedCode(A$,NULL) ' Process the function key ELSE CALL Send1Line(A$) ' Echos the character END IF END SUB The NULL variable on the ExtendedCode is used only by Incomm, and you shouldn't pass anything to it in place of it, and its not used to return anything to your program. Now the GetInput routine we have above is pretty good. It will accept input from the keyboard and from remote, check for a extended code and process it, otherwise it will echo the character. You can also write your own chat routine, but use our code by calling Incomm with the second parameter as a 5. This will print the "Sysop started chat at" and the "Hello, this is" lines, and then will handle the input and color for you, then once the sysop presses ESC to end the chat, it will print the "Sysop ended chat at" and return control to you. So basically, by passing a 5 as the second parameter forces a chat. Example: CALL Incomm("",5,No,15) ' Forces a chat Carrier loss processing ---------------------- Sometimes in more complex doors, its necessary to process a carrier drop yourself in order to save and wrap up files. You could turn carrier checking off, but its best if you use the CarrierLossError method. What you do is set CarrierLossError to YES and when carrier is dropped, a error number 255 will be forced, and if you have a ON ERROR trapping processing in your program, you will be able to catch it, and then let Door Source finish off the rest. For an example, please refer to the example program ERRDEMO.BAS. Door Source 4.0B Programmer's Manual - Page 32 How a door works ---------------- Understanding how a door works is good to know so that you can better plan your door. Here's a simple diagram on what happens: BBS Creates the interface file and exits \|/ Door's batch file is run \|/ |--> Door loads and reads in the interface file | \|/ Door Source | The door opens the communications port if needed handles this | \|/ with your | User interacts with the door program | \|/ |--> Door eventually exits, updating the interface file \|/ BBS reloads and reads in the interface file \|/ User continues using the bbs The DOORSORC.INT file sets up the necessary DECLAREs for the routines and the functions, it then sets up the COMMON SHARED block which lets you share variables with Door Source, like Baud&. Then it sets up a few constants, and then calls InitDoor, then the Door Source library takes over, and reads the configuration file, initialize its variables and then opens the com port for access. Then control is returned to you and your program picks up from their setting the program's name and version, etc,... While you're doing other processing, Door Source is ALWAYS looking at the com port, keeping received data in its buffer until you're ready for it. Door Source monitors everything for you, from carrier detection to characters being sent to characters being received, all behind the scenes. Door Source 4.0B Programmer's Manual - Page 33 Converting from Door Source 3.2 or before to 4.0 ------------------------------------------------ There are a few changes in how you call routines from 3.2 and before. Here's the list and how to change your program to fit 4.0 without major restructuring. The easiest way to change things is using the QuickBasic search and replace feature from the edit menu. * Routine AllTrun is now a function, you use it like this: A$ = AllTrun$(A$) * Routine HighScores has a extra parameter. The new third parameter lets you output its output to a already open file by passing the file number, but if you pass a 0, it outputs to the screen. CALL HighScores(Score, ScoreDataFile$, OutputFileNumber) * Routine Windows has a few parameters changes, the text foreground and text background have been deleted since WindowPrint and WindowInput do all window processing. Windows in your program will need to be re-written because of this. CALL Windows(ULR, ULC, LRR, LRC, Foreground, Background, Border, Shadow) * Routine Windows has two new borders, they are: 3 - Double horizontal Single vertical 4 - Single horizontal Double vertical * Routine DayOfWeek moved into ScriptCMD. I1$="DAYOFWEEK":CALL ScriptCMD * Routine MenuManager parameters have been changed, the Select$ parameter has been deleted, since now ANSI.Select$ and NonANSI.Select$ (COMMON SHARED variables) are now used for the select string. BarForeground and BarBack have been added, they have the foreground and background color for the selection bar. CALL MenuManager(Menu$(),Center,TextColor,NumberOfSelections, BarForeground, BarBackground, BarnumberSelected) * Routine SysopPage now has an extra parameter, this extra one is used to return a variable in, not to pass one. It returns a 1 (YES) if the page was answered. CALL SysopPage(Answered) * Routine ErrorLevelSet has been removed because of environment conflicts. Door Source 4.0B Programmer's Manual - Page 34 Summary of new features ----------------------- LOCAL command line switch added NETWORK command line switch added Up.Key$ and Down.Key$ variables added SysopPage changed PageSound.1, PageSound.2, and PageSound.3 added Page.String$ added F5 (Shell to DOS) added F3 (Printer toggle) added GameInfoUpdate routine added GameInfoCol added Table$ and Default.Table$ added PromptIncomm routine added No.Abort added MenuManager changed Parser changed WindowPrint and WindowInput routines added ExtendedCode routine added Protected.Input$ added BlockSend routine added RainbowSend routine added Windows routine changed DayOfWeek routine moved into ScriptCMD RandNum function fixed EntryIncomm added AllTrun routine changed into a function CheckCarrier routine added Baud& variable added CarrierLossError added Carrier.Check added ChangeDTR, ChangeCTS, and ChangeRTS added IRQ command line parameter added ADDR command line parameter added PS2 command line parameter added HighScores changed ALL ROUTINES optimized to run faster, and to be more compact Door Source 4.0B Programmer's Manual - Page 35 Appendix A - CALL Syntax ------------------------ CALL QSend(Text$, Enter) CALL BackSpace(Text$) CALL ExtendedCode(Text$,NULL) CALL BeepSpeaker() CALL NL(Number.Of.Lines) CALL Send(Text$, Bell, Enter, Color.To.Use) CALL Incomm(Text$, Enter, Limit.Field, Color.To.Use) CALL ANSIMusic(Music$, Music) CALL GameInfoUpdate(Text$, Enter, Color.To.Use, Color.Background) CALL BackSpaceOver() CALL Center(Text$) CALL ClrScrn CALL ColorEasy(Text$, Color.To.Use, Enter) CALL DoorBusy() CALL ErrorLevelSet(Error.Level) CALL ExitDoor() CALL GetTime(Hours, Minutes, Seconds, SinceMid#) CALL HighScores(Score, Score.FileName$, OutputFileNumber) CALL MenuManager(Menu$(), Center, TextColor, Number.Of.Bars, Select.Color, BarForeground, BarBackground, BarSelected) CALL MoveCursor(X,Y) CALL Parser(SearchFor$, SearchIn$, Array$(), ErrCode) CALL ReadUsers(ErrCode) CALL ScriptCMD() CALL Sorter(Array$(), How.Many.Elements) CALL SysopPage(Answered) CALL TimeConvert(Hours, Minutes, New.Time$) CALL ViewFile(FileName$, Check.For.GFile, MorePrompts, EnterPrompt) CALL WaitASec(How.Many.Seconds.To.Wait) CALL Windows(ULR, ULC, LRR, LRC, Fore, Back, Border, Shadow) CALL WriteUsers(ErrCode) CALL BlockSend(Array$(), Center, Lines.To.Send) CALL WindowPrint(Text$, Row, Col, Fore, Back) CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back) CALL RainbowSend(Text$, Bell, Enter, Color.To.Use) CALL PromptIncomm(Text$, Default$, DefaultColor, LimitField, Color.To.Use) CALL EntryIncomm(Text$, LimitField, FieldColor, Color.To.Use) CALL ShellToDos(Shell.String$) Door Source 4.0B Programmer's Manual - Page 36 Appendix B - Optimizing your door --------------------------------- The best way to optimize a door program can be divided into two parts. 1) The first part is cleaning up your code. This would mean elimination of most or all GOTOs and GOSUBs, elimination of as many constants as possible, and elimination of repetition in your code. 2) The second part is compiling from the command line. QuickBasic compiles with some unneeded options when you select the Make EXE command from the Run menu. You might need the error trapping flag (/X) if you have a ON ERROR statement in your program, and you might need the switch for dynamic arrays (/AH) if you're using them. Here's a sample compilation for a NON-STANDALONE program: BC MYPROG; LINK /EX MYPROG.BAS,MYPROG.EXE,,BRUN45.LIB+DOORSORC.LIB For a STANDALONE program, use this: BC MYPROG/O; LINK /EX MYPROG.BAS,MYPROG.EXE,,BCOM45.LIB+DOORSORC.LIB These parameters will compile the to the most compact format. You can also use PKLITE to compress it more. Door Source 4.0B Programmer's Manual - Page 37 Appendix C - Common Questions ----------------------------- Q: How do I read in additional information from the configuration file? A: To read in more information, simply INPUT from file #1 after you call ClrScrn for the first time. Make sure to close it when you're done. Here's an example: ' $INCLUDE:'DOORSORC.INT' PROGNAME$="Example" RELEASE$="1.0" CALL ClrScrn INPUT #1, ExtraInfo CLOSE #1 Door Source doesn't read past the fourth line of the configuration file, so you can put whatever you please there. Q: How do I test a door from inside QuickBasic? A: You must have first loaded QuickBasic with the /L option specifying the Door Source library. For example: QB MYDOOR /L DOORSORC Then you will need to setup the command line parameters by setting the COMMAND$, you do this from the Run menu from Modify COMMAND$. Now, as long as your configuration file, bbs interface file, and all other files you need exist, you can press F5 and test your door from QuickBasic. Q: Should I compile as a stand-alone door? A: It's up to you. A stand-alone door will not need the BRUN45.EXE, but it will make your door significantly larger, and compiling not as a stand-alone will save space. Door Source will work fine either way. Q: What does the error "Error opening port -1" mean? A: It means that you have specified a invalid serial port, and you should check your bbs interface file or your bbs's setup. Door Source 4.0B Programmer's Manual - Page 38 Appendix D - Variable Reference ------------------------------- The first part of this reference is of the global variables, the second is of the global UserBlock type declaration. Variable Name Purpose ------------- ------------------------------------------------------ ARG$ Input from user, returned by Incomm routine SYSDPATH$ Drive/Path/Filename of bbs interface file BBSName$ Name of BBS running on SysopNM$ Sysop FULL name CALLNAME$ Caller's FULL name TrueBaud& True baud rate of the caller Baud& Baud rate of caller PROGNAME$ Name of your door RELEASE$ Version of your door ANSI Ansi Flag (1 = On 0 = Off) I1$,I2$,I3$ Input variables to script commands O1$,O2$,O3$ Output variables from script commands User.Color Color that user input will be display in BackGroundColor Color to use for background when displaying Exit.Dor.1$ First line of ExitDoor message Exit.Dor.2$ Second line of ExitDoor message Exit.Dor.Clr1 Color of first line Exit.Dor.Clr2 Color of second line UserF$ First name of caller UserL$ Last name of caller Caps Convert all input to caps (1 = Yes 0 = No) Page.Bell Page bell toggle (-1 = On 0 = Off) Caller.Alarm Caller alarm (-1 = On 0 = Off) Sysop.Next Sysop next on toggle (-1 = On 0 = Off) Hang.Up Exit to DOS after log off toggle (-1 = On 0 = Off) User.Record Record number of user Network Network active (1 = Yes 0 = No) Display.Toggle Display on/off toggle (ignored by DS -1 = On 0 = Off) Printer.Toggle Printer on/off (-1 = On 0 = Off) BusyFlag A signal to ExitDoor that DoorBusy routine is in use UserFile$ Drive/Path/Filename of USERS file (PCBoard ONLY!) Up.Key$ Key to be used for scrolling up in MenuManager Down.Key$ Key to be used for scrolling down in MenuManager Parity Parity of user calling (7 or 8 data bits) Filter Incomm filtering active (filters all high ascii out) BusyFile$ Drive/Path/Filename of busy file for DoorBusy routine SysFirst$ Sysop's first name SysLast$ Sysop's last name CommPort Communacations port being used (1-8) Last.Clr.Used Last color used in a call to Send EchoKey STOPS echoing keys to remote user (1 = Yes 0 = No) No.Enter.Send Incomm doesn't send enter when done (1 = Yes 0 = No) File.Missing$ String ViewFile$ displays when file is not found Door Source 4.0B Programmer's Manual - Page 39 BBSType$ Type of BBS in use (PCB14, PCB121, PCB122, WILDCAT, RBBS, or DOORSYS) Node Node caller is on (works on with PCBoard systems) TabSpace Send will tab to this column before sending InverseText Reverses the text colors (Foreground/Background switch) Sysop Sysop is on (1 = Yes 0 = No) BlinkText Send will make text blink Not.Around$ String to show when Sysop doesn't answer page PARAM$ Extra command-line parameters that DS didn't use Page.String$ String to display while paging PageSound.1 First tone of page PageSound.2 Second tone of page PageSound.3 Third tone of page GameInfoCol Column to start printing on game status line Default.Table$ Table containing a unaltered filter Table$ Specific filtering of characters for Incomm KeyBoardTimeOut Number of SECONDS for a keyboard time out Protected.Input$ Incomm displays this instead of what user types ANSI.Select$ Menu Manager's ANSI selection string NonAnsi.Select$ Menu Manager's NON-ANSI selection string Carrier.Check Disables carrier checking (1 = Yes 0 = No) CarrierLossError Causes ExitDoor to generate a error 255 if carrier is dropped. No.Abort Disables CTRL-X, CTRL-K keys from aborting screens (1 = Yes 0 = No) AutoMore Automatically prints more prompts/press any key prompts Lines.Since Number of lines printed since last more/press prompt Door Source 4.0B Programmer's Manual - Page 40 This is the reference for the UserBlock global variable PCBOARD/PCBOARD.SYS / WILDCAT/CALLINFO.BBS / / RBBS/DORINFO1.DEF / / / DOOR.SYS / / / / Variable Type P W R D Description ------------------- ----------- - - - - ------------------------- CityState AS STRING * 24 Y Y Y Y City and state of user Password AS STRING * 12 Y Y Y User's Password BusinessPhone AS STRING * 13 Y Y User's Business/Data phone VoicePhone AS STRING * 13 Y Y Y User's Voice/Home phone LastDateOn AS STRING * 20 Y Y Y Last date user was on LastTimeOn AS STRING * 5 Y Last time user was on ExpertMode AS STRING * 1 Y Y Y Expert mode "Y" or "N" ProtocolType AS STRING * 5 Y Y Y Protocol selected LastDirListing AS STRING * 10 Y Y Last date viewed dir SecurityLevel AS INTEGER Y Y Y Y Security Level for user TimesOn AS INTEGER Y Y Y Number of times on before PageLength AS INTEGER Y Y Page length for user TotalUploads AS INTEGER Y Y Y Total # of uploads made TotalDownloads AS INTEGER Y Y Y Total # of downloads made DailyDownloadBytes AS DOUBLE Y # of download bytes left UserComment AS STRING * 30 Y User Comment field SysopComment AS STRING * 30 Y Sysop Comment field ElapsedTime AS INTEGER Y Y Elapsed Time on system 1 Subscription AS STRING * 20 Y SubscriptionExpire AS STRING * 20 Y AreaRegistration AS STRING * 50 Y Y Y Areas user has access to AreaExpire AS STRING * 50 Y AreasToScan AS STRING * 50 Y TotalDownloadBytes AS DOUBLE Y Y Y Total bytes downloaded TotalUploadBytes AS DOUBLE Y Total bytes uploaded DeleteFlag AS STRING * 1 Y Flag to delete user TimeEnteredDoor AS STRING * 5 Y Y Y Y Time user entered door AreaFrom AS INTEGER Y Y Area user exited from MemorizedMessage AS LONG Y Memorized message # TimeCalled AS STRING * 5 Y Y Time user called bbs DailyDownloadTotal AS INTEGER Y Total downloads TODAY MaxDownloadLimit AS DOUBLE Y Max downloads TODAY LastRead AS INTEGER Y Message last read MaxDownloadKLimit AS DOUBLE Y Y Y Max d/l K TODAY ExpirationDate AS STRING * 10 Y LR0 AS STRING * 4 Y LR1 AS STRING * 4 Y LR2 AS STRING * 4 Y . . LR39 AS STRING * 4 Y Door Source 4.0B Programmer's Manual - Page 41 Appendix E - Script Commands Reference -------------------------------------- Script commands are several small routines packed all into one. In order to access them, you set the according variables, and then make a call to ScriptCMD routine. For example, if you wanted to display a Press [ANY KEY] to continue prompt, you could do this: I1$ = "PRES" CALL ScriptCMD Variables I1$, I2$, and I3$ are all INPUT variables that store information for the routine to use. O1$, O2$, and O3$ are all OUTPUT variables that return information from the routine to you. I1$ is always the name of the routine you're calling inside of ScriptCMD. You only have to specify the first 4 letters of the word unless stated in the documentation. Door Source 4.0B Programmer's Manual - Page 42 LTRIM Purpose: To trim all leading spaces Name in ScriptCMD: LTRIM Remarks: This routine is a simple truncation routine to remove all leading spaces from a string. Parameters Passed: I2$ - The string to be truncated Parameters Returned: O1$ - The truncated string Door Source 4.0B Programmer's Manual - Page 43 RTRIM Purpose: To trim all trailing spaces Name in ScriptCMD: RTRIM Remarks: This routine is a simple routine to truncate all trailing spaces from a string. Parameters Passed: I2$ - The string to be truncated Parameters Returned: O1$ - The truncated string Door Source 4.0B Programmer's Manual - Page 44 Upper Case Purpose: To convert a string to all upper case Name in ScriptCMD: UPPER Remarks: This routine will convert a string into all upper case Parameters Passed: I2$ - The string to be converted Parameters Returned: O1$ - The converted string Door Source 4.0B Programmer's Manual - Page 45 Lower case Purpose: To convert a string to all lower case Name in ScriptCMD: LOWER Remarks: This routine will convert a string into all lower case Parameters Passed: I2$ - The string to be converted Parameters Returned: O1$ - The converted string Door Source 4.0B Programmer's Manual - Page 46 More Prompt Purpose: To display a more prompt Name in ScriptCMD: MORE Remarks: This will display a more prompt and allow the user to select Yes to continue, No to abort, and C to go non-stop. It will return a Y (for yes), a N (for no), or a C (for non-stop) in O1$ Parameters Passed: None Parameters Returned: O1$ - Contains a Y, N, or C Door Source 4.0B Programmer's Manual - Page 47 Press Any Key Purpose: To display a Press [ANY KEY] to continue prompt Name inside ScriptCMD: PRESS Remarks: This will display a Press [ANY KEY] to continue prompt and then wait for the key to be pressed: Parameters Passed: None Parameters Returned: None Door Source 4.0B Programmer's Manual - Page 48 Exist Purpose: To check if a file exists Name inside ScriptCMD: EXIST Remarks: This will check for the existence of the file specified. Parameters Passed: I2$ - Drive/Path/Location of file to check for Parameters Returned: O1$ - If the file exists (Y = Yes N = No) Door Source 4.0B Programmer's Manual - Page 49 Name conversion Purpose: To convert a name into proper upper and lower case Name inside ScriptCMD: NAMECASE Remarks: This will take a name like "DR. JOHN DOE" and properly convert it into "Dr John Doe" Parameters Passed: I2$ - The name to be converted Parameters Returned: O1$ - The converted name Door Source 4.0B Programmer's Manual - Page 50 Coding and Decoding Purpose: To code and decode a string Name inside ScriptCMD: CODER Remarks: This is a simple coding routine that will resist causal attempts to break it. It will code and decode with the same password. The longer the password, the better the protection you will have. The password shouldn't have any high ASCII characters in it. Parameters Passed: I2$ - String to be coded/decode I3$ - Password to code/decode with Parameters Returned: O1$ - The coded/decoded string Door Source 4.0B Programmer's Manual - Page 51 Reverse Bits Purpose: To reverse the bits in a string Name inside ScriptCMD: REVERSEBITS (MUST USE ENTIRE NAME!) Remarks: This will take all of the characters in a string and reverse it's bits. This is a simple, but easy to break coding routine. To unreverse the bits, just call the routine again. Parameters Passed: I2$ - The string to bit reverse Parameters Returned: O1$ - The bit reversed string Door Source 4.0B Programmer's Manual - Page 52 Reverse Characters Purpose: To reverse the order of characters in a string Name inside ScriptCMD: REVERSECHARS (MUST USE ENTIRE NAME!) Remarks: This changes the order of characters in a string so that the first is last, and the last is first, and so on throughout the entire string. To decode it, simply call the routine again. Parameters Passed: I2$ - The string to be reversed Parameters Returned: O1$ - The reversed string Door Source 4.0B Programmer's Manual - Page 53 Appendix F - Command Reference ------------------------------ Each command is shown in a set format. The format is as follows: Name of routine Purpose: States the prupose of the routine Remarks: Tells you the general information on the routine and how to use it. Parameters Passed: Tells you what parameters to the routine and what they are for. Parameters Returned: Tells you what parameters are returned and what is in them. Example: A short little program showing the usage of the routine See Also: (on some routines) Gives you a reference to other routines that do nearly the same thing or that work with this routine. Door Source 4.0B Programmer's Manual - Page 54 AdjustTimeLimit Purpose: To adjust the user's time remaining Syntax: CALL AdjustTimeLimit(Minutes) Remarks: This will adjust the user's time remaining up or down depending on the number you pass it. You *MUST* pass a variable and not a number as the parameter, otherwise the time will not change. The TimeLeft: on the status line will be updated on the next call to the Send command. Parameters Passed: Minutes - The number of minutes to increase the user's time Parameters Returned: None Example: TimeAdjust = 10 CALL AdjustTimeLimit(TimeAdjust) ' Give 10 minutes TimeAdjust = -10 CALL AdjustTimeLimit(TimeAdjust) ' Take 10 minutes Door Source 4.0B Programmer's Manual - Page 55 AllTrun$ Purpose: To truncate all leading and trailing spaces from a string Syntax: Text$ = AllTrun$(Text$) Remarks: This will remove all of those leading and trailing spaces that are a result of random file input, use of STR$, and other functions of BASIC. Parameters Passed: Text$ - The string to remove leading and trailing spaces from Parameters Returned: Text$ - The string without leading and trailing spaces Example: Text$ = " These extra spaces will be removed " Text$ = AllTrun$(Text$) Door Source 4.0B Programmer's Manual - Page 56 ANSIMusic Purpose: To play ANSI music to those users who can use it Syntax: CALL ANSIMusic(Music$, Music) Remarks: Some communacations programs can support and play ANSI music but not all of them. Qmodem, for example, will play ANSI music. You should ask your users near the beginning of the program "Do you have ANSI music?" and if they answer yes, then set Music to Yes (1) otherwise set it to No (0). You don't have to use Music, but whatever variable you store that value in should always be the second parameter of the call to this routine. The music string can be anything that the BASIC command PLAY would be able to play. The local speaker won't play the music unless the page bell is on. Parameters Passed: Music$ - The music to be played Music - If the user supports ANSI music or not (1 = Yes 0 = No) Parameters Returned: None Example: Music = Yes Music$ = "ABCDEFG" CALL ANSIMusic(Music$, Music) Door Source 4.0B Programmer's Manual - Page 57 BackSpace Purpose: To backspace on the local and remote screen and also erase the proper character in the string passed Syntax: CALL BackSpace(Text$) Remarks: This will allow you to write your own input routines for use, and when a user presses the backspace key, call this routine and it will send the proper backspacing codes and erase the backspaced character from the string passed. Parameters Passed: Text$ - A string that will the backspace will be preformed on Parameters Returned: Text$ - The new string with the last character erased Example: IF KeyPressed$ = CHR$(8) THEN CALL BackSpace(Text$) END IF Door Source 4.0B Programmer's Manual - Page 58 BackSpaceOver Purpose: To erase what is already on a line Syntax: CALL BackSpaceOver Remarks: This routine will backspace over everything to column 1, erasing everything on that line. If you have a prompt that you'd like to erase or something, this is the routine to call to erase it. Parameters Passed: None Parameters Returned: None Example: CALL BackSpaceOver See Also: BackSpaceToCol Door Source 4.0B Programmer's Manual - Page 59 BackSpaceToCol Purpose: To backspace over to the specified column Syntax: CALL BackSpaceToCol(Col) Remarks: This will backspace over from the current column all the way to the column specified. This is useful if the user inputed a improper response to a prompt and you want to erase just the user's input. Parameters Passed: Col - The column to backspace over to Parameters Returned: None Example: CALL Send("Backspace to here->this will be erased!",No,No,10) CALL BackSpaceToCol(20) See Also: BackSpaceOver Door Source 4.0B Programmer's Manual - Page 60 BeepSpeaker Purpose: To sound the local and remote speaker Syntax: CALL BeepSpeaker Remarks: Calling BeepSpeaker instead of sending a bell code to the screen and com port is better since it will always beep the remote speaker but won't make the local speaker sound unless the page bell is on. Parameters Passed: None Parameters Returned: None Example: CALL BeepSpeaker Door Source 4.0B Programmer's Manual - Page 61 BlockSend Purpose: To send a large amount of information to both displays Syntax: CALL BlockSend(Array$(), Center, Lines.To.Send) Remarks: This will send a large pre-programmed amount of data to the local and remote displays. Color can only be set and changed via @X codes. This routine is good for programmed in documentation, or menus. Parameters Passed: Array$() - The array to be displayed Center - Center text to be displayed Lines.To.Send - Number of array elements to display Parameters Returned: None Example: Array$(1) = "This will be displayed" Array$(2) = "Using the BlockSend routine" CALL BlockSend(Array$(), No, 2) See Also: ColorEasy, RainbowSend, Send, QSend Door Source 4.0B Programmer's Manual - Page 62 Center Purpose: To aid in centering strings for output Syntax: CALL Center(Text$) Remarks: This will strip out all @X codes and substitute in the proper text for substitution codes and will then set TabSpace to equal the correct column to make the string look centered. The string that you pass is NOT modified by this routine. This routine also will NOT print out the results but only set TabSpace. Parameters Passed: Text$ - The string to be centered Parameters Returned: None Example: Text$ = "This will be centered!" CALL Center(Text$) CALL Send(Text$, No, Yes, 10) Door Source 4.0B Programmer's Manual - Page 63 ChangeCTS Purpose: To raise or lower the CTS flag Syntax: CALL ChangeCTS(OnOff) Remarks: This will turn on or off the CTS (Clear To Send) flag which is used to tell the other modem that it is okay to send characters. Modem that don't preform error checking or UARTS that don't have buffers may require CTS flow-control to be on during high speed file transfers. Parameters Passed: OnOff - Whether you want the CTS on or off (1 = Yes(On) 0 = No(Off)) Parameters Returned: None Example: CALL ChangeCTS(No) ' Turns CTS off See Also: ChangeDTR, ChangeRTS Door Source 4.0B Programmer's Manual - Page 64 ChangeDTR Purpose: To raise or lower the DTR Syntax: CALL ChangeDTR(OnOff) Remarks: If you want to drop the carrier on someone, this is one of the best ways to do it. Turning the DTR off normally will cut a person off-line, but not always. Parameters Passed: OnOff - Whether you want the DTR on or off (1 = Yes(On) 0 = No(Off) Parameters Returned: None Example: CALL ChangeDTR(No) ' Turns off DTR See Also: ChangeCTS, ChangeRTS Door Source 4.0B Programmer's Manual - Page 65 ChangeRTS Purpose: To raise or lower the RTS flag Syntax: CALL ChangeRTS(OnOff) Remarks: The RTS (Request To Send) flag is uesd by most auto-dial modems to see if a computer is ready to recieve data from the modem. If the RTS signal isn't detected, some modems may refuse to accept modem commands or send result codes. Parameters Passed: OnOff - Whether you want the RTS on or off (1 = Yes(On) 0 = No(Off)) Parameters Returned: None Example: CALL ChangeRTS(No) ' Turns RTS off See Also: ChangeDTR, ChangeCTS Door Source 4.0B Programmer's Manual - Page 66 CheckCarrier Purpose: To check if a carrier is present Syntax: CALL CheckCarrier(CarrierPresent) Remarks: This will (as long as Carrier.Check is set to 0) return a Yes (1) or a No (0) in the parameter depending on if the carrier is present. If the global variable Carrier.Check is set to 1, then this routine will return ALWAYS a Yes (1). Parameters Passed: None Parameters Returned: CarrierPresent - Tells if the carrier is present (1 = Yes 0 = No) Example: CALL CheckCarrier(CarrierPresent) IF CarrierPresent = Yes THEN CALL Send("You're still connected!", No, Yes, 10) END IF Door Source 4.0B Programmer's Manual - Page 67 CheckTimeLeft Purpose: To tell you how many minutes a user has left on the system Syntax: TimeRemaining = CheckTimeLeft Remarks: This function will return the number of minutes that the user currently on has left for this call. Be careful not to assign the value returned to a variable named TimeLeft because doing so will modify Door Source's variable and cause the user's time to go berserk! Parameters Passed: None Parameters Returned: TimeRemaining - The number of minutes left the user has Example: CALL Send("("+STR$(CheckTimeLeft)+" min. left )", No, No, 14) See Also: AdjustTimeLimit Door Source 4.0B Programmer's Manual - Page 68 ClrScrn Purpose: To clear the local and remote screens Syntax: CALL ClrScrn Remarks: This will effectively clear the screen for both sides using the fastest method that the caller can use. Setting BackGroundColor previous to calling this routine will cause the entire screen to be that color! Parameters Passed: None Parameters Returned: None Example: CALL ClrScrn Door Source 4.0B Programmer's Manual - Page 69 ColorEasy Purpose: To colorize a string and output it Syntax: CALL ColorEasy(Text$, Color.To.Use, Send.Enter) Remarks: If you have a string that you'd like to colorize without having to bother with multiple calls to Send or with @X codes, then use this routine. It will colorize A-Z, a-z, 0-9, and punctuation all in different colors. The Color.To.Use that you specify will affect the output of color over the whole text, experiment with different values to best fit what you need. Parameters Passed: Text$ - The string to be colorized and displayed Color.To.Use - This will vary the output for the different colors used in coloring the text Send.Enter - Send a CR/LF sequence once displaying is finished Parameters Returned: None Example: Text$ = "This will be VERY colorful!!" CALL ColorEasy(Text$, 10, Yes) See Also: BlockSend, RainbowSend, Send, QSend Door Source 4.0B Programmer's Manual - Page 70 CommInkey$ Purpose: To get a key from just the remote keyboard Syntax: Character$ = CommInkey$ Remarks: This works just like INKEY$ and CommKeyInkey$, except it will take input ONLY from the com port. If there are no characters waiting to be read, then it will return a null. Parameters Passed: None Parameters Returned: Character$ - The character read from the com port Example: DO LOOP UNTIL (CommInkey$ <> "") OR (INKEY$ <> "") See Also: CommKeyInkey$ Door Source 4.0B Programmer's Manual - Page 71 CommKeyInkey$ Purpose: To get one character from the local or remote keyboard Syntax: Character$ = CommKeyInkey$ Remarks: This will check the local keyboard and the com port buffer for keys waiting to be read, if one is found, it will read it and return it, otherwise it will return a null. If you want to wait for a key to be pressed, you should put this routine in a WHILE loop. Parameters Passed: None Parameters Returned: Character$ - Either null (if no key was pressed local or remote) or a key from the keyboard or com port buffer. Example: DO Character$ = CommKeyInkey$ LOOP UNTIL Character$ <> "" See Also: Incomm, CommInkey$ Door Source 4.0B Programmer's Manual - Page 72 CopyAFile Purpose: To quickly copy a file without shelling to DOS Syntax: CALL CopyAFile(Source$, Destination$, ErrCode) Remarks: This will copy a file without the pitfalls of shelling to DOS to do it or of special complex programming. It will return a error code if an error occured. Parameters Passed: Source$ - Drive/Path/Filename of the file to be copied Destination$ - Drive/Path/Filename of the file to be created Parameters Returned: ErrCode - If a error occured during the copy (1 = Yes 0 = No) Example: Source$ = "MYFILE.TXT" Destination$ = "MYFILE2.TXT" CALL CopyAFile(Source$, Destination$, ErrCode) Door Source 4.0B Programmer's Manual - Page 73 DayOfWeek Purpose: To calculate the which day of the week it is Syntax: Day = DayOfWeek Remarks: This routine will return a value from 1 to 7 indicating which day of the week it is. A 1 is Sunday, 2 is Monday, and so on. Parameters Passed: None Parameters Returned: Day - A number from 1-7 representing the day of the week Example: IF DayOfWeek = 1 THEN CALL Send("It's SUNDAY!", No, Yes, 14) ELSE CALL Send("It's not sunday!", No, Yes, 10) END IF Door Source 4.0B Programmer's Manual - Page 74 DoorBusy Purpose: To keep a door from being used by two nodes at once Syntax: CALL DoorBusy Remarks: If you aren't going to program multi-node support, call this routine so that multinode systems won't have problems running your door. You have to set the global variable BusyFile$ to the drive/path/filename of a "lockout file" that will be the signal to other nodes that the door is in use. If another node is using your door, then this routine will call DoorBusy and not return control to your program. Parameters Passed: None Parameters Returned: None Example: BusyFile$ = "MYDOOR.NET" CALL DoorBusy Door Source 4.0B Programmer's Manual - Page 75 EntryIncomm Purpose: To provide a field showing maximum length of input for prompt Syntax: CALL EntryIncomm(Text$, MaxLength, FieldColor, Color.To.Use) Remarks: This is a handy routine to for larger fields (3 characters and larger) that lets the user know what the limit is on the field size by printing above the prompt a (------) field indicator showing the maximum number of characters allowed. Parameters Passed: Text$ - Prompt to display MaxLength - Maximum number of characters to allow for input (Required to be greater than 1) FieldColor - The color of the (---) field above the prompt Color.To.Use - The foreground color for the prompt itself Parameters Returned: ARG$ - The input received Example: See PRMTDEMO.BAS Text$ = "Enter your name:" CALL EntryIncomm(Text$, 20, 10, 11) ' This would output ' (--------------------) ' Enter your name: See Also: PromptIncomm, Incomm Door Source 4.0B Programmer's Manual - Page 76 ExtendedCode Purpose: To let you trap F-keys in your own I/O routines Syntax: CALL ExtendedCode(CodeToProcess$, NULL) Remarks: If you are writing your own version of Incomm, and would like to take advantage of Door Source's F-Key processing routines, call this with the key pressed and it will take the necessary action, which may be updating the status bar or shelling to DOS. Parameters Passed: CodeToProcess$ - The two character code of the key pressed NULL - This variable shouldn't be used by your routine, it is only used by Door Source and is specified only to maintain compatibility. Parameters Returned: None Example: A$ = INKEY$ IF LEN(A$)>1 THEN ' Extended code CALL ExtendedCode(A$, NULL) END IF Door Source 4.0B Programmer's Manual - Page 77 ExitDoor Purpose: To close the com port and update the bbs interface file Syntax: CALL ExitDoor Remarks: Whenever you want to end your door, you MUST call this routine. NEVER let your door simply just come to an end or have the END or SYSTEM command in it. This routine will uphold the DTR and cleanup Door Source's variables, handlers, etc,... It will also update the bbs interface file with the current information. After calling this routine, control will not be returned to your door. Parameters Passed: None Parameters Returned: None Example: CALL ExitDoor Door Source 4.0B Programmer's Manual - Page 78 FileExist Purpose: To detect is a file exists on a disk Syntax: Exists = FileExist(FileName$) Remarks: If you're opening files or preforming something with files you should check, before attempting use, if they exist and not assume that they are there, otherwise your program will generate a error and most likely crash the board it was running on. Parameters Passed: FileName$ - Drive/Path/Filename to the file to be checked for Parameters Returned: Exists - If the file exists or not (-1 = Yes 0 = No) Example: IF FileExist("MYFILE.FIL") THEN CALL Send("It exists!", No, Yes, 12) END IF Door Source 4.0B Programmer's Manual - Page 79 FileOpen Purpose: To aid in opening files in a better, easier way Syntax: FileNumber = FileOpen(FileName$, Access$, Sharing, Length) Remarks: When you want to open a file and you don't know what the next available file number is, or you don't want to refer to files by their number, or if you don't want to have to fool with checking if a network is active every time a file is opened, this routine is what you should call. It will find the next available file number and open the file according to your specifications and return the file number to you in a variable so you can use it in place of a number. Parameters Passed: FileName$ - This is the name of the file to be opened Access$ - The method in which you want to open the file for access. I - Sequential Input O - Sequential Output A - Append (Write at end of file) R - Random Read/Write B - Binary Read/Write Sharing - Will open files to be shared if specified and a network is active (1 = Yes 0 = No) Length - For random and binary files only, this will open the file with this as the record length. Parameters Returned: FileNumber - This is the variable you'd use for I/O with the file. It will contain a -1 if the file wasn't found that you tried to open only if you're trying to do sequential input. Example: FileNumber = FileOpen("MYFILE.FIL", "O", Yes, 0) PRINT #FileNumber, "This is in the file" CLOSE #FileNumber FileNumber = FileOpen("MYFILE.FIL", "I", Yes, 0) INPUT #FileNumber, DataFromFile$ CLOSE #FileNumber Door Source 4.0B Programmer's Manual - Page 80 GameInfoUpdate Purpose: To write to the 25 line of the game line of the status line Syntax: CALL GameInfoUpdate(Text$, Send.Enter, ColorFore, ColorBack) Remarks: If you want a game status line, you should use this routine to update line 25 (which will be the game status line). It works just like the PRINT command would work with a few differences. The Send.Enter really doesn't advance to the next line, but resets the column pointer (GameInfoCol) to 1. If you want to start printing someplace other than where you are, just set GameInfoCol to the column number. See the Advanced Programming section for a detailed explanation of how this command works. WARNING: You HAVE to use the DSGAME.INT in your main module instead of DOORSORC.INT otherwise this routine will not work! Parameters Passed: Text$ - String to be displayed on line 25 Send.Enter - Reset GameInfoCol to 1 after displaying (1 = Yes 0 = No) ColorFore - Foreground color to use ColorBack - Background color to use Parameters Returned: None Example: Text$ = "This is on the game status line!" CALL GameInfoUpdate(Text$, No, 0, 7) Door Source 4.0B Programmer's Manual - Page 81 GetTime Purpose: To separate the time into hours, minutes, and seconds Syntax: CALL GetTime(Hours, Minutes, Seconds, SinceMid#) Remarks: This will take the current time and return it to you in a separated form. Parameters Passed: None Parameters Returned: Hours - The hour Minutes - The minute Seconds - The second SinceMid# - The number of seconds since midnight Example: CALL GetTime(Hours, Minutes, Seconds, SinceMid#) CALL Send("Its "+STR$(Hours)+" o'clock", No, Yes, 10) See Also: TimeConvert Door Source 4.0B Programmer's Manual - Page 82 HighScores Purpose: To make a high score bulletin Syntax: CALL HighScores(Score, HighScoreFile$, OutputNumber) Remarks: This will take the user's score and use the high score data file specified, update the information, and then either display a bulletin or save it to disk. The high score data file, if non-existent will be created, its a random access file and can't be read/modified in a text editor. Compression can be done with the compression utility included with the Door Source archive. You will need to open the file for output before calling this routine if you want to direct the output to a file, this also allows you to create a header (on screen or in the file) for your bulletin. The format of where HighScores places the information is like this: <--21 spaces-------->(NAME OF USER)<---29 spaces--->(SCORE) John Doe 100 Jane Doe 50 Parameters Passed: Score - Score for user HighScoreFile$ - Name of the random access data file that HighScores creates OutputNumber - The filenumber that output should go to, if 0 then output goes to screen Parameters Returned: None Example: ScoreDataFile$ = "MYSCORE.SCO" Score = 569 ScoreBlt = 1 OPEN "SCORES.BLT" FOR OUTPUT AS #1 CALL HighScores(Score, ScoreDataFile$, ScoreBlt) Door Source 4.0B Programmer's Manual - Page 83 Incomm Purpose: To receive data from the keyboard and com port Syntax: CALL Incomm(Text$, Send.Enter, Max.Characters, Color.To.Use) Remarks: This is the basic input routine, it will check the keyboard and the remote keyboard for input. There are several variables that affect input for this routine, and they are all listed here: Protected.Input$ - Incomm will show this character in place of what is really typed. Setting this to "" will cause normal display of input TabSpace - The string to be displayed will be tabbed to this column User.Color - The user's input will be displayed in this color Caps - Incomm will covert input to all caps before returning (1 = Yes 0 = No) No.Enter.Send - After input is completed, a CR/LF won't be sent (1 = Yes 0 = No) EchoKey - Will make input not show up on the screens at all (1 = Yes 0 = No) Filter - This will filter out high ascii characters (128+) (1 = Yes 0 = No) Table$ - Set this to the only keys you want to be accepted if you want to limit the user to a few keys. Set it to Default.Table$ to restore it to normal. BackGroundColor - This is the background color for the prompt and input. Parameters Passed: Text$ - String to be sent as a prompt Send.Enter - Send a CR/LF AFTER the prompt and BEFORE input (1 = Yes 0 = No) Max.Characters - The maximum number of character to accept Setting this to a -1 (or Hockey) will make Incomm take the first character it gets and not wait for ENTER to be pressed before returning. (0 = No limit -1 = Hockey < 1 = Limit) Color.To.Use - Foreground color of prompt Door Source 4.0B Programmer's Manual - Page 84 Parameters Returned: ARG$ - The input received Example: ' You don't need to reset all of these variables each ' time you call incomm, they are show here just so you ' can see how they work. Caps = Yes ' Turn input to all caps Protected.Input$ = "*" ' Show * instead of letters Table$="ABCDEFGHIJKLMNOPQRSTUVWXYZ" ' Only accept A-Z Text$="Enter your name:" CALL Incomm(Text$, No, No, 10) Protected.Input$ = "" ' Show what is typed CALL Incomm(Text$, No, 25, 10) ' Limit to 25 characters See Also: CommInkey$ Door Source 4.0B Programmer's Manual - Page 85 MenuManager Purpose: To make a scroll bar menu Syntax: CALL MenuManager(Menu$(), Center, TextClr, Bars, SlctClr, BarFore, BarBack, BarSelected) Remarks: This will create a nice selectable menu with a scroll bar for ANSI users to scroll up and down. Non-ANSI users will see the menu, but will be forced to just enter a number and will have no scroll bar. You shouldn't have more than 20 selections on the menu, and all should be numbered. This routine is affected by several variables which are: Up.Key$ - The key to move the bar up (Default to +) Down.Key$ - The key to move the bar down (Default to -) ANSI.Select$ - Selection string displayed for ANSI users NonANSI.Select$ - Selection string displayed for NON-ANSI users Parameters Passed: Menu$() - An array with all the menu selections in it Center - Center the selections while displaying TextClr - Color for selections Bars - Number of selections in array SlctClr - Color for ANSI.Select$ or NonANSI.Select$ string BarFore - Foreground color for scroll bar BarBack - Background color for scroll bar Parameters Returned: BarSelected - The bar selected by the user Example: See MENUDEMO.BAS included with Door Source Door Source 4.0B Programmer's Manual - Page 86 MoveCursor Purpose: To position the cursor on the screen Syntax: CALL MoveCursor(X, Y) Remarks: Call this routine to position the cursor anywhere on the screen in the upper 22/23 lines (depending on if there is a game status line). This routine will not move the cursor if the user is not in ANSI mode. Parameters Passed: X - The row (vertical) Y - The column (horizontal) Parameters Returned: None Example: CALL MoveCursor(10, 10) Door Source 4.0B Programmer's Manual - Page 87 Parser Purpose: To separate data in a string with a delimiter Syntax: CALL Parser(SearchFor$, SearchIn$, ParArray$(), ErrCode) Remarks: This will take a string and look for the character specified and store the data in the array, it then repeats this process over and over until the end of the string has been reached. This can be handy to store numbers in a compact form for storage in a file. Parameters Passed: SearchFor$ - The string (delimiter) to search for SearchIn$ - The string to search in and to parse Parameters Returned: ParArray$() - Contains the data from SearchIn$ but separated ErrCode - Will greater than 1 is a error occurred Example: SearchFor$ = "*" SearchIn$ = "100*200*300*400*500*" CALL Parser(SearchFor$, SearchIn$, ParArray$(), ErrCode) FOR X = 1 TO 5 CALL Send(ParArray$(X), No, Yes, 10) NEXT ' This would output: ' 100 ' 200 ' 300 ' 400 ' 500 Door Source 4.0B Programmer's Manual - Page 88 NL Purpose: To send the specified number of times a CR/LF sequence Syntax: CALL NL(Number.Of.Times) Remarks: This will send a CR/LF sequence the number of times you tell it to. This is base routine for all routines to advance to the next line. Parameters Passed: Number.Of.Times - The number of times to display the CR/LF sequence. Parameters Returned: None Example: CALL NL(3) ' Print 3 CR/LF sequences See Also: Send Door Source 4.0B Programmer's Manual - Page 89 PromptIncomm Purpose: To provide a very formatted input field with a prompt Syntax: CALL PromptIncomm(Text$, Default$, DefaultColor, MaxLength, Color.To.Use) Remarks: This will make a little ( ) area for input to be inside of for ANSI users, non-ANSI users will just have a regular prompt. This routine also allows to easily add a "default" to the prompt. Parameters Passed: Text$ - Prompt to display Default$ - "Default" field. Some predefined ones are: Default1 = (Enter=no) Default2 = (Enter=none) Default3 = (Enter=quits) DefaultColor - Foreground color for default text MaxLength - Maximum number of characters (Required to be greater than 0) Color.To.Use - Foreground color for prompt Parameters Returned: ARG$ - The input received Example: See PRMTDEMO.BAS Text$ = "Enter your name" CALL PromptIncomm(Text$, Default3, 15, 10, 11) IF AllTrun$(ARG$) = "" THEN ' Process default ELSE ' Process other END IF ' This would output ' Enter your name (Enter=quits) ? ( ) ' The input would be displayed inside the ( ) See Also: EntryIncomm, Incomm Door Source 4.0B Programmer's Manual - Page 90 QSend Purpose: To send a string local and remote quickly without the extra bells and whistles of Send. Syntax: CALL QSend(Text$, Send.Enter) Remarks: QSend is a very basic sending routine that simply sends the given string to the local and remote screens. @X and other substitution codes are the only form of color control in the strings passed. Extra variables and parameters that affect Send don't affect QSend. Parameters Passed: Text$ - The string to be sent Send.Enter - Send a CR/LF after sending is complete (1 = Yes 0 = No) Parameters Returned: None Example: Text$ = "This will be displayed in the last color used." CALL QSend(Text$, Yes) See Also: BlockSend, ColorEasy, RainbowSend, Send, QSend Door Source 4.0B Programmer's Manual - Page 91 RainbowSend Purpose: To display text in a color, rainbow like form Syntax: CALL RainbowSend(Text$, Bell, Enter, Color.To.Use) Remarks: This is a creative way to display text to both displays. It will take the color given to use, and rotate through the colors making a very colorful display. Experiment with different colors to find the most desirable effect. Parameters Passed: Text$ - Text to be displayed Bell - Sound the remote speaker, and local is page bell is on Enter - Send a CR/LF sequence once displaying is done Color.To.Use - Foreground color to display text in Parameters Returned: None Example: Text$ = "This will be displayed" CALL RainbowSend(Text$, No, Yes, 10) See Also: BlockSend, ColorEasy, Send, QSend Door Source 4.0B Programmer's Manual - Page 92 RandNum Purpose: To generate a random number within a specified range Syntax: Number = RandNum(Low, High) Remarks: This is handy to generate a random number in the range that you need it. It will generate a completely random number. Parameters Passed: Low - The lowest number desired High - The highest number desired Parameters Returned: Number - The random number generated Example: CALL Send("The number is "+STR$(RandNum(10,20)), No, Yes, 10) Door Source 4.0B Programmer's Manual - Page 93 ReadUsers Purpose: To read from the PCBoard 14.x users file Syntax: CALL ReadUsers(ErrCode) Remarks: This will read the user's record from the PCBoard user file specified in the global variable UserFile$. The data will be read into the global type declaration UserBlock (Which is shown in Appendix D - Variable Reference). For other bbs types, most of the data is loaded directly from the bbs interface file, and calling a routine to read the users file is not necessary. The best way to set UserFile$ is to add on another line to the configuration file and read it in yourself after the first call to ClrScrn. Parameters Passed: None Parameters Returned: ErrCode - This is the error code is a error occurred 1 - Users file not found 2 - Wrong BBS type 3 - UserFile$ not set to Drive/Path/Filename of users file Example: See BLCKDEMO.BAS ' UserFile$ already set earlier in the program CALL ReadUsers(ErrCode) CALL Send("You're from "+STR$(UserBlock.CityState), No,Yes,10) See Also: WriteUsers Door Source 4.0B Programmer's Manual - Page 94 Send Purpose: To display a string to local and remote screens Syntax: CALL Send(Text$, Send.Bell, Send.Enter, Color.To.Use) Remarks: This is the basic sending routine and it will display to the local and remote screens. This routine will accept @X codes and other substitution codes and display the proper things in response to it. A few variables affect this routine's output, here's a list: BackGroundColor - Background color to be used TabSpace - The text will be tabbed to this column for display Parameters Passed: Text$ - The string to be displayed Send.Bell - Will sound the speaker on the remote and will also sound the local ONLY if the page bell is on. (1 = Yes 0 = No) Send.Enter - Send a CR/LF sequence once displaying is done (1 = Yes 0 = No) Color.To.Use - Foreground color to display in Parameters Returned: None Example: Text$ = "This will be displayed!" CALL Send(Text$, No, Yes, 10) See Also: BlockSend, ColorEasy, RainbowSend, QSend, WindowPrint Door Source 4.0B Programmer's Manual - Page 95 ShellToDOS Purpose: To efficiently shell to DOS in order to avoid conflicts Syntax: CALL ShellToDOS(Shell.String$) Remarks: This will let Door Source completely wrap up all of its operations (actually close the com port, but uphold DTR and carrier) so that shelling to a external file transfer program is possible without a conflict of interrupts. This command duplicates what a SHELL command would do in BASIC, but gives Door Source a chance to clean up itself. Parameters Passed: Shell.String$ - This is the command to be executed once the shell is started Parameters Returned: None Example: Shell.String$ = "DIR >OUTPUT.TXT" CALL ShellToDOS(Shell.String$) Door Source 4.0B Programmer's Manual - Page 96 Sorter Purpose: To sort numbers into descending order Syntax: CALL Sorter(ParArray$(), Number.To.Sort) Remarks: If you need to sort numbers parsed with parser, or other numbers in a STRING array, then call this routine and it will sort it into a descending order. Parameters Passed: ParArray$() - The array of numbers to be sorted Number.To.Sort - The number of array elements to sort Parameters Returned: ParArray$() - The sorted array Example: ParArray$(1) = "400" ParArray$(2) = "200" ParArray$(3) = "600" CALL Sorter(ParArray$(), 3) FOR X=1 TO 3 CALL Send(ParArray$(X), No, Yes, 10) NEXT X ' Output would be this: ' 600 ' 400 ' 200 Door Source 4.0B Programmer's Manual - Page 97 SysopPage Purpose: To page the sysop if the page bell is on Syntax: CALL SysopPage(Answered) Remarks: This routine will check the page bell, and if on, will page the sysop using the paging sounds. If the page wasn't answered or the sysop isn't around then it will return a 0 in the parameter. This routine is affect by several global variables, which are: PageSound.1 - Sound #1 to be in the "beep" sound of the page PageSound.2 - Sound #2 to be in the "beep" sound of the page PageSound.3 - Sound #3 to be in the "beep" sound of the page Page.String$ - String to show while paging the sysop Not.Around$ - String to show when the sysop is not around Parameters Passed: None Parameters Returned: Answered - If the page was answered (1 = Yes 0 = No) Example: CALL SysopPage(Answered) Door Source 4.0B Programmer's Manual - Page 98 TimeConvert Purpose: To convert from two variables into the HH:MM format Syntax: CALL TimeConvert(Hours, Minutes, NewTime$) Remarks: This will combine hours and minutes into the HH:MM format. Parameters Passed: Hours - The hour Minutes - The minute Parameters Returned: NewTime$ - The hour and minute in HH:MM format Example: Hours = 10 Minutes = 30 CALL TimeConvert(Hours, Minutes, NewTime$) CALL Send(NewTime$+" is the next event time.", No, Yes, 10) See Also: GetTime Door Source 4.0B Programmer's Manual - Page 99 ViewFile Purpose: To display a file to the local and remote screens Syntax: CALL ViewFile(FileName$, ANSICheck, MorePrompts, ExitPrompt) Remarks: This will display a ANSI or non-ANSI screen to both screens. If you specify to check for a ANSI version of the file, then Door Source will take the filename given, add a G to it, and look for the existence of that file for ANSI users. You can enable more prompts for documentation, or leave them off for long ANSI screens. The exit prompt is a "Press [ANY KEY] to continue" prompt that is display at the end of the file if told to do so. The user can abort the screen at any point by pressing the space bar, CTRL-X, or CTRL-K. If the No.Abort global variable is set to 1 (Yes) then the user can't abort the display. ANSI files should NOT exceed 80 characters in length per line. Parameters Passed: FileName$ - Drive/Path/Filename of file to display ANSICheck - Check for ANSI version of file for ANSI users (1 = Yes 0 = No) MorePrompts - Display more prompts every 23 lines (1 = Yes 0 = No) ExitPrompts - Displays a "Press [ANY KEY]" prompt at end of display (1 = Yes 0 = No) Parameters Returned: None Example: FileName$ = "MYFILE" CALL ViewFile(FileName$, Yes, No, Yes) FileName$ = "MYDOCS.DOC" CALL ViewFile(FileName$, No, Yes, Yes) Door Source 4.0B Programmer's Manual - Page 100 WaitASec Purpose: To delay the program the specified number of seconds Syntax: CALL WaitASec(Number.Of.Seconds) Remarks: Using the SLEEP command, or a FOR loop to delay a program isn't often a good idea in a door because the user could drop carrier. This routine will delay the program correctly for the number of seconds specified and will also keep track of the carrier signal. Parameters Passed: Number.Of.Seconds - Number of seconds to delay program Parameters Returned: None Example: CALL WaitASec(5) ' delay 5 seconds Door Source 4.0B Programmer's Manual - Page 102 WindowInput Purpose: To display a prompt and get input from inside a window Syntax: CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back) Remarks: This works just like the Incomm routine, but does the I/O inside of a window created with the Windows routine. The MaxLength should be just right so that input won't overflow the window border and cause problems with erasing it. Parameters Passed: Text$ - Prompt to be displayed MaxLength - Maximum number of characters allowed in input Row - Row to display at (horizontal) Col - Column to display at (vertical) Fore - Foreground color to display prompt in Back - Background color to display prompt in Parameters Returned: ARG$ - The input received Example: Text$ = "Enter your name:" MaxLength = 25: Row = 13: Col = 12 Fore = 15: Back = 1 CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back) See Also: Windows, WindowPrint Door Source 4.0B Programmer's Manual - Page 102 WindowPrint Purpose: To display text inside of a window Syntax: CALL WindowPrint(Text$, Row, Col, Fore, Back) Remarks: This is an easy way of displaying text anywhere inside of a window made with the Windows routine. It can also be used for quick short displays that aren't at the current cursor location. Parameters Passed: Text$ - Text to be displayed Row - Row to display at (horizontal) Col - Column to display at (vertical) Fore - Foreground color to display with Back - Background color to display with Parameters Returned: None Example: Text$ = "This will be displayed" Row = 12: Col = 12: Fore = 15: Back = 1 CALL WindowPrint(Text$, Row, Col, Fore, Back) See Also: Windows, WindowInput Door Source 4.0B Programmer's Manual - Page 103 Windows Purpose: To draw window on the local and remote screens Syntax: CALL Windows(ULR, ULC, LRR, LRC, Fore, Back, Border, Shadow) Remarks: This will draw a border enclosed area on the screen, and will even make a shadow if requested. Printing and input is done inside the window with WindowPrint and WindowInput. This is a ANSI only routine, and shouldn't be used with non-ANSI users. Parameters Passed: ULR - Upper Lefthand row ULC - Upper Lefthand column LRR - Lower Righthand row LRC - Lower Righthand column Fore - Foreground color to use for border Back - Background color to use for border and to fill inside Border - The border number 1 - Single line 2 - Double line 3 - Double horizontal, Single vertical 4 - Single horizontal, Double vertical Shadow - Makes a shadow on the window (1 = Yes 0 = No) Parameters Returned: None Example: ULR = 10: ULC = 10 LRR = 20: LRC = 70 CALL Windows(ULR, ULC, LRR, LRC, 11, 1, 4, Yes) See Also: WindowInput, WindowPrint Door Source 4.0B Programmer's Manual - Page 104 WriteUsers Purpose: To write to PCBoard 14.x user file Syntax: CALL WriteUsers(ErrCode) Remarks: This will write the user's record to the PCBoard user file specified in the global variable UserFile$. The data written will be from the global type declaration UserBlock (Which is shown in Appendix D - Variable Reference). For other bbs types, most of the data is written when ExitDoor is called, and calling a routine to write to the users file is not necessary. The best way to set UserFile$ is to add on another line to the configuration file and read it in yourself after the first call to ClrScrn. Parameters Passed: None Parameters Returned: ErrCode - This is the error code is a error occurred 1 - Users file not found 2 - Wrong BBS type 3 - UserFile$ not set to Drive/Path/Filename of users file Example: See BLCKDEMO.BAS ' UserFile$ already set earlier in the program UserBlock.CityState = "Anytown, USA" CALL ReadUsers(ErrCode) See Also: ReadUsers